home *** CD-ROM | disk | FTP | other *** search
/ Shareware Super Platinum 8 / Shareware Super Platinum 8.iso / mac / PROGTOOL / CX201E.ZIP;1 / CXSUB.DOC < prev    next >
Encoding:
Text File  |  1994-03-02  |  12.0 KB  |  318 lines
  1.  
  2. CXSUB routines
  3. --------------------------------------------------------------------------
  4.    As you know, Cx provides a very low level interface to data compression.
  5.    Many application designers, however, may be able to use a higher level
  6.    interface.  The CXSUB routines provide a high level, application
  7.    independent interface to Cx data compression.  The CXSUB routines have
  8.    been carefully designed to allow easy integration into existing
  9.    applications.  You may be able to use the CXSUB routines in your
  10.    applications, but if not, they may be instructive in explaining
  11.    the usage of Cx.
  12.  
  13.  
  14. The Source Code
  15. --------------------------------------------------------------------------
  16.    Source code for the CXSUB routines is found in the files:
  17.  
  18.       CXSUB.C     -  C source code
  19.       CXSUB.H     -  C header file
  20.       CXSUB.PAS   -  Turbo Pascal source code
  21.       VBCXSUB.BAS -  Visual BASIC source code
  22.  
  23.  
  24. Programming Interface
  25. --------------------------------------------------------------------------
  26.  
  27.    CXSUB Error Codes
  28.    ------------------------------------------------------------------
  29.       CXSUB_ERR_OPENS   -  Could not open source.
  30.       CXSUB_ERR_OPEND   -  Could not open destination.
  31.       CXSUB_ERR_NOMEM   -  Insufficient memory.
  32.       CXSUB_ERR_READ    -  Could not read from source.
  33.       CXSUB_ERR_WRITE   -  Could not write to destination.
  34.       CXSUB_ERR_CLOSE   -  Could not close destination.
  35.       CXSUB_ERR_INVALID -  source file is invalid or corrupt
  36.  
  37.  
  38.    cx_error_message(error)
  39.    ------------------------------------------------------------------
  40.    PURPOSE:
  41.       Return an English error string from a Cx or CXSUB error.
  42.  
  43.    PARAMETER:
  44.       error    -  error code (CX_ERR* or CXSUB_ERR*)
  45.  
  46.    RETURN:
  47.       An English error message, or "unknown" if the error code is
  48.       unknown.
  49.  
  50.  
  51.    cx_compress_file(dst, src, method, bsize, tsize)
  52.    ------------------------------------------------------------------
  53.    PURPOSE:
  54.       Compress any size or type of file to another file.
  55.  
  56.    PARAMETERS:
  57.       dst      -  destination file name
  58.       src      -  source file name
  59.       method   -  Compression method (CX_METHOD*)
  60.       bsize    -  compression buffer size (1-CX_MAX_BUFFER)
  61.       tsize    -  temporary buffer size (CX_C_MINTEMP-CX_D_MINTEMP)
  62.  
  63.    RETURN:
  64.       CX_ERR_*       -  Cx error.
  65.       CXSUB_ERR_*    -  CXSUB error.
  66.       0              -  No error.
  67.  
  68.    NOTES:
  69.       For maximum compression specify bsize and tsize as large as possible.
  70.  
  71.       See section 'CXSUB Single File Compression' for more information.
  72.  
  73.  
  74.    cx_decompress_file(dst, src)
  75.    ------------------------------------------------------------------
  76.    PURPOSE:
  77.       Decompress a file compressed with cx_compress_file.
  78.  
  79.    PARAMETERS:
  80.       dst      -  destination file name
  81.       src      -  source file name
  82.  
  83.    RETURN:
  84.       CX_ERR_*       -  Cx error.
  85.       CXSUB_ERR_*    -  CXSUB error.
  86.       0              -  No error.
  87.  
  88.    NOTES:
  89.       If dst is not specified (NULL in C, '' in Pascal, "" in Visual
  90.       BASIC), an integrity check only will be performed.
  91.  
  92.       See section 'CXSUB Single File Compression' for more information.
  93.  
  94.  
  95.    cx_compress_ofile(ofile, ifile, method, bsize, tsize)
  96.    ------------------------------------------------------------------
  97.    PURPOSE:
  98.       Compress any size or type of file to another file, with files
  99.       previously opened.
  100.  
  101.    PARAMETERS:
  102.       ofile    -  opened output file
  103.       ifile    -  opened input file
  104.       method   -  Compression method (CX_METHOD*)
  105.       bsize    -  compression buffer size (1-CX_MAX_BUFFER)
  106.       tsize    -  temporary buffer size (CX_C_MINTEMP-CX_D_MINTEMP)
  107.  
  108.    RETURN:
  109.       CX_ERR_*       -  Cx error.
  110.       CXSUB_ERR_*    -  CXSUB error.
  111.       0              -  No error.
  112.  
  113.    NOTES:
  114.       For maximum compression specify bsize and tsize as large as possible.
  115.  
  116.       See section 'CXSUB Single File Compression' for more information.
  117.  
  118.  
  119.    cx_decompress_ofile(dst, src)
  120.    ------------------------------------------------------------------
  121.    PURPOSE:
  122.       Decompress a file compressed with cx_compress_(o)file, with
  123.       files previously opened.
  124.  
  125.    PARAMETERS:
  126.       ofile -  opened output file
  127.       ifile -  opened input file
  128.  
  129.    RETURN:
  130.       CX_ERR_*       -  Cx error.
  131.       CXSUB_ERR_*    -  CXSUB error.
  132.       0              -  No error.
  133.  
  134.    NOTES:
  135.       See section 'CXSUB Single File Compression' for more information.
  136.  
  137.  
  138. CXSUB Single File Compression (SFC)
  139. --------------------------------------------------------------------------
  140.    This section contains general and language specific information about
  141.    the following CXSUB functions:
  142.  
  143.       cx_compress_file     -  file name interface
  144.       cx_decompress_file   -  file name interface
  145.  
  146.       cx_compress_hfile    -  file handle interface
  147.       cx_decompress_hfile  -  file handle interface
  148.  
  149.  
  150.    Overview
  151.    ---------------------------------------------------------------------
  152.    The CXSUB Single File Compression (SFC) routines provide an easy way to
  153.    compress and decompress one file to another.
  154.  
  155.    There are two interfaces.  One is based on file names.  Using this
  156.    interface is not much harder than specifying:
  157.  
  158.          "Compress file A to file B"    or
  159.          "Decompress file B to file C"
  160.  
  161.    Of course, the decompression routine will only work on files compressed
  162.    with the compression routine.  The other interface is based on file
  163.    handles.  A file handle is simply a way to reference an open file.
  164.    This interface is provided to allow for future routines based on the
  165.    SFC routines.  It is possible, for example, to design an archive file
  166.    format that uses the handle based interface.
  167.  
  168.    All of the provided SFC source code writes and reads the same file
  169.    format.
  170.  
  171.  
  172.    File Format
  173.    ---------------------------------------------------------------------
  174.    The file format is a sequence of variable length 'blocks'.  Blocks are
  175.    produced by reading data from a file to be compressed.  The amount of
  176.    data read in each pass is known here as the 'original buffer size' or
  177.    BSIZE.
  178.  
  179.    If, for example, you are compressing a 1000 bytes file, and BSIZE is
  180.    100 bytes, 10 blocks will be produced.  BSIZE is a parameter to the
  181.    file compression routines (parameter bsize).
  182.  
  183.    A block has 4 pieces of information:
  184.  
  185.       2 bytes     -  original buffer size       (BSIZE)
  186.       2 bytes     -  compressed buffer size     (CSIZE)
  187.       2 bytes     -  16 bit CRC (from CX_CRC)   (DATACRC)
  188.       CSIZE bytes -                             (DATA)
  189.  
  190.    The relation between these 4 pieces of information is:
  191.  
  192.       if BSIZE is the same as CSIZE, the original buffer could not be
  193.       compressed.  DATA contains uncompressed data.
  194.  
  195.       if BSIZE is not the same as CSIZE, the original buffer was successfully
  196.       compressed.  CSIZE will be strictly less than BSIZE.  DATA contains
  197.       compressed data.
  198.  
  199.       DATACRC is a 16 bit CRC computed on DATA.  Note that this means
  200.       DATACRC is computed on compressed data.
  201.  
  202.    To indicate the end of a compressed file, an abbreviated block is stored.
  203.    The abbreviated block is simply:
  204.  
  205.       2 bytes     -  original buffer size (0)
  206.  
  207.    As an example, compressing a 25 byte file with BSIZE equal to 10, where:
  208.  
  209.       bytes  0...9  compress to 7 bytes
  210.       bytes 10..19  can't be compressed
  211.       bytes 20..25  compress to 2 bytes
  212.  
  213.    The file data produced from the SFC compression routines will be:
  214.  
  215.       ------------------------------
  216.       2  bytes    -  10                block 1
  217.       2  bytes    -  7
  218.       2  bytes    -  DATACRC
  219.       7  bytes    -  compressed data
  220.       ------------------------------
  221.       2  bytes    -  10                block 2
  222.       2  bytes    -  10
  223.       2  bytes    -  DATACRC
  224.       10 bytes    -  uncompressed data
  225.       ------------------------------
  226.       2  bytes    -  5                 block 3
  227.       2  bytes    -  2
  228.       2  bytes    -  DATACRC
  229.       2  bytes    -  compressed data
  230.       ------------------------------
  231.       2  bytes    -  0                 block 4, Abbreviated end of file block
  232.  
  233.    Of course, you would typically use a BSIZE much larger than 10 bytes.
  234.    For maximum compression, you would use a BSIZE of CX_MAX_BUFFER.
  235.  
  236.  
  237.    Motivation / Questions / Expanding or Improving the SFC routines
  238.    ---------------------------------------------------------------------
  239.    The following questions and answers may provide insight into the
  240.    SFC functions.
  241.  
  242.       Q: Why are bsize and tsize parameters?  For maximum compression,
  243.          bsize should always be CX_MAX_BUFFER and tsize should always be
  244.          CX_C_MAXTEMP.
  245.       A: Some applications want or need to minimize memory usage.  By
  246.          keeping bsize and tsize parameters, the application can balance
  247.          memory usage and compression size.
  248.  
  249.  
  250.       Q: Why are both BSIZE and CSIZE stored?
  251.       A: By storing both, it is possible to handle uncompressable data.
  252.          If BSIZE is equal to CSIZE, the stored buffer is known to be
  253.          uncompressed.
  254.  
  255.  
  256.       Q: Why is a CRC computed on the compressed buffer as opposed to the
  257.          original buffer?
  258.       A: Testing has determined that a CRC on compressed buffers is better
  259.          able to detect errors than a CRC on original buffers.  In addition,
  260.          as compressed buffers are typically smaller than original buffers,
  261.          a CRC on a compressed buffer is quicker to compute.
  262.  
  263.  
  264.       Q: Why is the last block abbreviated?
  265.       A: Simply to save space.  By abbreviating the final block, it is
  266.          possible to save 4 bytes of storage for each compressed file.
  267.          Note, however, that this is a fairly arbitrary decision.  As
  268.          file I/O calls consume time, it may be desirable to store a
  269.          'complete' block.  This would eliminate up to 2 file I/O calls
  270.          per block when decompressing.
  271.  
  272.  
  273.       Q: Why isn't the compression method stored?
  274.       A: CX_DECOMPRESS can decompress any buffer compressed with CX_COMPRESS
  275.          without knowing beforehand the specific compression method used.
  276.  
  277.  
  278.       Q: What if I wanted to store an original files time stamp and/or
  279.          name in a compressed file?
  280.       A: This would be a fairly easy addition.  You could add a header
  281.          to the SFC file format.  As an example:
  282.  
  283.             4 bytes        -  files time stamp
  284.             1 byte         -  name length (NAMELEN)
  285.             NAMELEN bytes  -  file name
  286.  
  287.          The cx_compress_file and cx_decompress_file functions could be
  288.          modified to write, read and use this header information.  The only
  289.          additional routines you would have to call (included in most
  290.          languages) are for reading and writing a files time stamp.
  291.  
  292.  
  293.       Q: What if I wanted to extract valid data from a corrupt compressed
  294.          file?
  295.       A: This could be accomplished by expanding a block.  Instead of:
  296.          
  297.             2 bytes     -  original buffer size       (BSIZE)
  298.             2 bytes     -  compressed buffer size     (CSIZE)
  299.             2 bytes     -  16 bit CRC (from CX_CRC)   (DATACRC)
  300.             CSIZE bytes -                             (DATA)
  301.  
  302.          You could specify:
  303.  
  304.             4 bytes     -  header like '$CX$'
  305.             4 bytes     -  physical file location     (POS)
  306.             2 bytes     -  original buffer size       (BSIZE)
  307.             2 bytes     -  compressed buffer size     (CSIZE)
  308.             2 bytes     -  16 bit CRC (from CX_CRC)   (DATACRC)
  309.             CSIZE bytes -                             (DATA)
  310.  
  311.          With a corrupt file, you could search the file for the block header
  312.          ($CX$).  After finding a header, you would have all the information
  313.          you need to extract a valid original buffer.  If there are errors
  314.          when decompressing a block, you would know it is invalid.   Note
  315.          that smaller BSIZE's will have more potential for recovery as each
  316.          block will effect less data.
  317.  
  318.